Updated 👍

Alex, thanks a lot for documenting this new feature so fast.

While merging I did some very minor changes ((e926d7c)) ... but I also promoted the mention about where to define this new env var to a caution because I think this is important to avoid readers frustration (e.g. if they define this env var in the default .env file thinking that Symfony will read that value and load the custom file).

Thanks Javier!

Hello and sorry, this feature has been misinterpreted. The variable can't be set before calling DotEnv. It's only an internal variable, like SYMFONY_DOTENV_VARS, that is set by the DotEnv class when a file is loaded.
You can document how to change the path to the .env file:

The custom path can be set in many ways:

• Doing a call to (new Dotenv())->bootEnv(dirname(__DIR__).'my/custom/path/to/.env');
• In composer.json: "extra": { "runtime": { "dotenv_path": "my/custom/path/to/.env" }
• With the env var: $_SERVER['APP_RUNTIME_OPTIONS'] = ['dotenv_path' => 'my/custom/path/to/.env'];

I'll send another PR to fix this, thanks for the explanation Jérôme!

I'm sorry but this description is wrong. This var is not about changing the location of the dot env files. It's about exposing where the dotenv files are so that the apps itself can know about it.
/cc @GromNaN